| ListQualify |
|
 |
| Description
|
|
Inserts a string at the beginning and end of list elements.
|
| |
| Returns
|
|
A copy of the list, with qualifier before and after the specified element(s).
|
| |
| Category
|
|
List functions
|
| |
| Function syntax |
ListQualify(list, qualifier [, delimiters ] [, elements ])
|
| |
| History
|
|
ColdFusion MX: Changed behavior: as the elements parameter value, you must specify "all" or "char"; otherwise, ColdFusion throws an exception. (In earlier releases, the function ignored an invalid value, and used "all"; this was inconsistent with other functions.)
|
| |
| Parameters
|
| |
| Parameter |
Description |
| list |
A list or a variable that contains one. |
| qualifier |
A string or a variable that contains one. Character or string to insert before and after |
| |
the list elements specified in the elements attribute. |
| delimiters |
A string or a variable that contains one. Character(s) that separate list elements. |
| |
Default: comma. |
| |
If this parameter contains more than one character, ColdFusion uses the first |
| |
character as the delimiter and ignores the remaining characters. |
| elements |
all: all elements |
| |
char: elements that are composed of alphabetic characters |
|
| |
| Usage
|
|
The new list might not preserve all of the delimiters in the list.
|
|
ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.
|
| |
Example<cfquery name = "GetEmployeeNames" datasource = "cfsnippets">
SELECT FirstName, LastName
FROM Employees
</cfquery>
<h3>ListQualify Example</h3>
<p>This example uses ListQualify to put the full names of the
employees in the query within quotation marks.</p>
<cfset myArray = ArrayNew(1)>
<!--- loop through query; append these names successively to the last element -
-->
<cfloop query = "GetEmployeeNames">
<cfset temp = ArrayAppend(myArray, "#FirstName# #LastName#")>
</cfloop>
<!--- sort that array descending alphabetically --->
<cfset myAlphaArray = ArraySort(myArray, "textnocase")>
<!--- show the resulting array as a list --->
<cfset myList = ArrayToList(myArray, ",")>
<cfoutput>
<p>The contents of the unqualified list are as follows: </p>
#myList#
</cfoutput>
<!--- show the resulting alphabetized array as a qualified list with
single quotes around each full name. --->
<cfset qualifiedList1 = ListQualify(myList,"'",",","CHAR")>
<!--- output the array as a list --->
<cfoutput>
<p>The contents of the qualified list are as follows: </p>
<p>#qualifiedList1#</p>
</cfoutput>
<!--- show the resulting alphabetized array as a qualified list with quotation
marks around each full name. We use " to denote quotation marks
because the quotation mark character is a control character. --->
<cfset qualifiedList2 = ListQualify(myList,""",",","CHAR")>
<!--- output the array as a list --->
<cfoutput>
<p>The contents of the second qualified list are: </p>
<p>#qualifiedList2#</p>
</cfoutput>
|